Summary

Adds comprehensive UX testing framework for demo preparation and fixes Neo4j connection issue caused by import path shadowing.

UX Testing & Demo Preparation

New Documentation

• dev/ux-testing-checklist.md - Comprehensive page-by-page testing guide

  • All 9 pages covered (Home, Chat, Files, Map, Labels, Links, Settings, etc.)
  • Core workflows, edge cases, and UX polish checks for each page
  • Status tracking (✅/⚠️/❌/🔲) system
  • Demo readiness checklist
  • Gap tracking for prioritizing issues

• DEMO_SETUP.md - Quick start guide for running and testing the app

  • Step-by-step startup instructions
  • Page navigation reference
  • Test data creation (3 different methods)
  • 5 common demo workflows
  • Troubleshooting guide
  • Configuration steps

• Updated existing docs

  • README.md: Added "Testing & Demo" section
  • dev/prompts.md: Added UX testing workflow

Testing Workflow

1. Start app using DEMO_SETUP.md
2. Work through dev/ux-testing-checklist.md page by page
3. Mark status and document issues
4. Create tasks for gaps
5. Iterate: fix → re-test → complete

Neo4j Import Shadowing Fix

The Problem

When starting the app with python -m scidk.app, Neo4j connections failed with:

• Error: type object 'GraphDatabase' has no attribute 'driver'
• HTTP 502 when trying to connect to Neo4j in Settings page

However, scidk-serve worked fine.

Root Cause

• Local neo4j/ test stub directory was shadowing the real neo4j package
• python -m scidk.app adds current directory to sys.path[0]
• Python found local stub before real package in .venv/lib/python3.x/site-packages/
• Stub only has empty GraphDatabase class without driver method

Solution Implemented

1. ✅ Created scidk/__main__.py that removes cwd from sys.path before importing
2. ✅ Updated pyproject.toml to exclude neo4j* and tests* from package builds
3. ✅ Documented stub purpose in .gitignore
4. ✅ Added comprehensive technical documentation in dev/reports/neo4j-import-issue-fix.md

Recommended Usage (Priority Order)

1. ✅ scidk-serve - Best, console script entry point
2. ✅ python -m scidk - Works with new __main__.py fix
3. ❌ python -m scidk.app - Avoid, causes shadowing issue

Testing

Manual Testing

• Verified neo4j import works with scidk-serve
• Verified neo4j import works with python -m scidk
• Confirmed GraphDatabase.driver attribute is accessible
• Tested Neo4j connection in Settings page (both methods work)

E2E Tests

• Existing E2E test coverage: 98.3% (117/119 elements)
• Tests still pass with new __main__.py

Files Changed

New Files

• DEMO_SETUP.md - Demo setup and troubleshooting guide
• scidk/__main__.py - Fixes import path for python -m scidk
• dev/ux-testing-checklist.md - Comprehensive UX testing guide
• dev/reports/neo4j-import-issue-fix.md - Technical analysis

Modified Files

• .gitignore - Document neo4j stub purpose
• README.md - Add Testing & Demo section
• pyproject.toml - Exclude test stubs from package
• dev/prompts.md - Add UX testing workflow

Related Issues

Resolves the Neo4j 502 connection error discovered during demo preparation.

Next Steps

After merge:

1. Follow DEMO_SETUP.md to start the app
2. Work through dev/ux-testing-checklist.md systematically
3. Identify and prioritize UX gaps
4. Iterate on fixes until demo-ready

🤖 Generated with Claude Code

Co-Authored-By: Claude noreply@anthropic.com